home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / hp48hor2 / rpl489.doc < prev    next >
Text File  |  1995-03-31  |  66KB  |  1,848 lines
  1.  
  2.                           Magic48ges presents: 
  3.  
  4.  
  5.                      ûûûûû  ûûûûû  û       û   ûûû 
  6.                       û   û  û   û û      ûû  û   û 
  7.                       û   û  û   û û     û û  û   û 
  8.                       ûûûû   ûûûû  û    û  û   ûûû 
  9.                       û û    û     û    ûûûûû û   û 
  10.                       û  û   û     û       û  û   û 
  11.                       û   û  û     ûûûû    û   ûûû 
  12.  
  13.  
  14.  
  15.              A SYSTEM-RPL DEVELOPMENT TOOLKIT FOR THE HP48 
  16.  
  17.  
  18.                               Version 2.02 
  19.  
  20.  
  21.        (c) 1993 by Detlef Mueller & Raymond Hellstern, Magic48ges 
  22.  
  23.  
  24. CONTENTS 
  25. íííííííí 
  26.  
  27.  
  28. 1. Introduction 
  29.     1.1 Copyrights & Acknowledgements 
  30.     1.2 The RPL48 Toolkit 
  31.     1.3 Requirements & Installation Instructions 
  32.     1.4 Abbreviations 
  33.  
  34. 2. <-RPL-> Library 
  35.     2.1    Overview 
  36.     2.2    The System-RPL Compiler/Decompiler 
  37.     2.3    The Saturn Assembler/Disassembler 
  38.     2.3.1 The Assembler Parameter Field Parser 
  39.     2.4    The Reference Table 
  40.     2.5    Command Reference 
  41.     2.6    Hooks 
  42.     2.7    Things to Notice 
  43.  
  44. 3. <-LIB-> Library 
  45.     3.1 Overview 
  46.     3.2 Control Variables 
  47.     3.3 Command Reference 
  48.     3.4 Things to Notice 
  49.  
  50. Appendix A - Quick Reference Guides 
  51.     A.1 <-RPL-> 
  52.     A.1.1 Commands 
  53.     A.1.2 Flag Usage 
  54.     A.1.3 Error Messages 
  55.     A.2 <-LIB-> 
  56.     A.2.1 Commands 
  57.     A.2.2 Flag Usage 
  58.     A.2.3 Error Messages 
  59.  
  60. Appendix B - A ->COD Example 
  61.  
  62. Appendix C - Ordering Information 
  63.  
  64.  
  65. 1. Introduction 
  66. ííííííííííííííí 
  67.  
  68.  
  69. 1.1 Copyrights & Acknowledgements 
  70. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  71.  
  72. All files of the RPL48 toolkit are copyrighted (c) by Detlef Mueller and 
  73. Raymond Hellstern - Magic48ges, 1991-1993 - unless otherwise noted. 
  74.  
  75. The RPL48 package is distributed in the hope that it will be useful, but 
  76. RPL48 is provided 'as is,' and is subject to change without notice. 
  77. D. Mueller and R. Hellstern make no warranty of any kind with regard to 
  78. the software or documentation, including, but not limited to, the implied 
  79. warranties of merchantability and fitness for a particular purpose. 
  80. D. Mueller and R.Hellstern shall not be liable for any error or for 
  81. incidental or consequential damages in connection with the furnishing, 
  82. performance, or use of this software and documentation. 
  83.  
  84. This version of RPL48 is a GiftWare release. You may use it as long as you 
  85. like without registration, but only for developing non-commercial software. 
  86.  
  87. Permission to copy the whole, unmodified RPL48 package is granted provided 
  88. that the copies are not made or distributed for resale (excepting nominal 
  89. copying fees). If you want to get your own, brand new version, and for further 
  90. information, please refer to Appendix C. 
  91.  
  92. It should be impossible to crash your '48 by using RPL48, but be warned: 
  93. no software is bug free ! 
  94.  
  95. We would like to thank the following people for their support: 
  96.  
  97.   Wlodek Mier-Jedrzejowicz    for presenting RPL48 to the world. 
  98.   Rick Grevelle            for the HACKIT library, the ->DIR command of 
  99.                                 <-LIB->, the base of the sys-stack, many 
  100.                                 suggestions, exiting talks and for sending 
  101.                                 us an HP48GX. 
  102.   Mika Heiskanen        for beta testing, lots of suggestions, MKROM, 
  103.                                 DEBUG, and for a great performance enhancement 
  104.                                 of the D->LIB and L->DIR commands. 
  105.   Douglas R. Cannon        for beta testing, lots of suggestions, and 
  106.                   for reviewing this document. 
  107.   Joseph K. Horn        for beta testing and suggestions, the `HP 48 
  108.                                 Resource Allocation Guideline; Library ID's`, 
  109.                                 SORTLS and for maintaining the '48 GDs. 
  110.   Carlos Ferraro        for beta testing and his friendship. 
  111.   Simone Rapisarda        for beta testing and many suggestions. 
  112.   Fatri Mohamed, 
  113.   Romain Desplats, 
  114.   Georg Hoppen            for suggestions and beta testing. 
  115.   James H. Cloos, 
  116.   Steve VanDevender, 
  117.   Chris Maksymiak        for suggestions. 
  118.   Jeoff Krontz,            for suggestions, beta testing, getting another 
  119.                   GX for Raymond, exiting talks, and.. 
  120.   Chris Spell            ..for maintaining the '48 archive at 
  121.                                 seq.uncwil.edu and for moderating 
  122.                                 comp.sources.hp48. 
  123.   Dennis York            for the kindly permission to publish the BNF 
  124.                                 parser generator example. 
  125.   W.C.Wickes & HP Corvallis    for the '48 and the RPL tools. 
  126.  
  127.  
  128. 1.2 The RPL48 Toolkit 
  129. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  130.  
  131. The RPL48 Toolkit provides more than 50 powerful commands to aid system RPL 
  132. and assembler programming and library development on a HP48. It consists of 
  133. three parts: 
  134.  
  135.     * library 1234, <-RPL->:5.00 - contains a sys-RPL compiler/decompiler 
  136.       and Saturn assembler/disassembler. 
  137.  
  138.     * library 1221, <-LIB->:2.0 - contains a library creator/splitter and 
  139.       many commands for handling libraries and un-/supported objects. 
  140.  
  141.     * a reference table which contains address/name pairs of ROM entry 
  142.       points. 
  143.  
  144. The main commands of RPL48 are modeled after the MesS-DOS programs RPLCOMP. 
  145. EXE, SASM.EXE and USRLIB.EXE which are provided by HP in the self extracting 
  146. archive TOOLS.EXE (available on several ftp sites and GD#4). This document 
  147. describes the interface to RPL48; it is not a sys-RPL or Saturn assembler 
  148. manual. Please refer to RPLMAN.DOC, RPLCOMP.DOC, USRLIB.DOC and SASM.DOC 
  149. (all contained in TOOLS.EXE) for learning and/or reference purposes. 
  150.  
  151. We assume that you are familar with the fundamentals of sys-RPL, Saturn 
  152. assembly and libraries. 
  153.  
  154.  
  155. 1.3 Requirements & Installation Instructions 
  156. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  157.  
  158. RPL48 should work on ROM versions A-M HP48 - it's tested on rev A, E, L, M 
  159. machines by the authors, and it's reported to run also on rev D and J. 
  160.  
  161. The <-RPL-> library is compiled to a fixed address; it MUST be stored in an 
  162. independent (FREEd) port (ie. it only works on a SX or GX), on a SX this can 
  163. be either port 1 or 2, on a GX this must be port 1 ! 
  164.  
  165. Because the whole RPL48 kit requires ~60kb of memory (including a reference 
  166. table made from the latest entries released by HP) it is recommended to store 
  167. it into a 128k RAM card. The <-LIB-> library was developed using the standard 
  168. methods, it can be stored and used in port 0 on any HP48; on a GX it's 
  169. limited to the ports 0 and 1, and must not be installed in the ports 2-33. 
  170.  
  171. For a complete installation of RPL48 it is neccessary that you have plugged 
  172. in a 128k RAM card (which must have ~60kb free space) in either port 1 or 2 
  173. of your SX, port 1 of your GX; the card must be set to R/W. Proceed as 
  174. follows: 
  175.  
  176.     a) remove all files of an earlier version 
  177.  
  178.     b) merge the port 
  179.  
  180.     c) set up RPL.TAB on your computer by renaming one of the two shipped 
  181.        reference tables or by creating an own one (see section '2.4 The 
  182.        Reference Table') 
  183.  
  184.     d) download RPL.TAB, LIB.LIB and RPL.LIB 
  185.  
  186.     e) recall RPL.TAB to the stack, purge RPL.TAB and store it as a backup 
  187.        object named RPL.TAB (case sensitive !) into port 0 (:0:RPL.TAB STO) 
  188.  
  189.     f) recall the two libraries, purge the variables containing the original 
  190.        copies and store the libraries into port 0 (two times 0 STO) 
  191.  
  192.     g) free the port, make sure that :0:1234 is the 1st entry of the list 
  193.        in level 2 for the FREE command ! (you can use 0 PVARS DROP to 
  194.        generate the base list) 
  195.  
  196.     h) warmstart the '48 (power cycle it, or press [ON]-[C]) 
  197.  
  198. As mentioned, <-RPL-> is compiled to an absolute address. Its config code 
  199. takes care of the address the library is stored at. On an SX, if neccessary, 
  200. the base addresses of the ports are swapped and an additional warmstart 
  201. is initiated automatically while executing the first warmstart after 
  202. installation. If the config code recognizes that it is impossible to change 
  203. to the correct address (ie. the library is stored in port 0, not the 1st 
  204. object of port 1 or 2 on a SX, or not the 1st object of port 1 on a GX), the 
  205. autoattach to the home directory is supressed and no (c)-message and no beeps 
  206. are generated. If the library did not attach itself, make sure it becomes the 
  207. 1st object of the desired port and execute a warmstart again. 
  208.  
  209. If you have installed an HP41 emulator card, <-RPL-> does not install because 
  210. the emulator uses a similar sheme to install itself to the same address (it 
  211. is also an absolute library) -- just remove the card. 
  212.  
  213. The <-RPL-> and the <-LIB-> libraries are not self-modifing - you can write 
  214. protect the card containing the libraries. 
  215.  
  216.  
  217. 1.4 Abbreviations 
  218. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  219.  
  220. LID   - library id; a number in the range 0..2047, part of any library, It 
  221.     is used by the HP firmware to identify libraries while resolving 
  222.     commands, messages etc. 
  223. |     - used in stack diagrams for 'or' 
  224.  
  225. Abbreviations denoting objects: 
  226.  
  227. ob    object of any type 
  228. xlib    named or unnamed library command 
  229. :x:y    tagged object - tag x, ob y 
  230. prg    program (secondary) 
  231. bak    backup 
  232. dir    directory 
  233. alg    algebraic 
  234. lib    library 
  235. libdta    library data 
  236. meta(t)    meta object, obn .. ob1 %n, all ob's are of the same type t 
  237.  
  238. All other abbreviations are defined in RPLMAN.DOC (like %, # etc.). 
  239.  
  240.  
  241. 2. <-RPL-> Library 
  242. íííííííííííííííííí 
  243.  
  244.  
  245. 2.1 Overview 
  246. ÄÄÄÄÄÄÄÄÄÄÄÄ 
  247.  
  248. <-RPL-> contains 17 commands, including a sys-RPL compiler (->RPL), a sys-RPL 
  249. decompiler (RPL->), a Saturn assembler (->COD), a Saturn disassembler (COD->) 
  250. a RPL.TAB browser (EC) and a medium font sys-stack environment (4/5/7). 
  251.  
  252.  
  253. 2.2 The System-RPL Compiler/Decompiler 
  254. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  255.  
  256. The compiler is a simple token based one pass LR compiler and implements a 
  257. grammatical subset of RPLCOMP.EXE. It accepts string objects containing a 
  258. token sequence, seperated by whitespace (NL,CR,Space,TAB etc.), as input. 
  259.  
  260. The output of the decompiler can be used as input for the compiler or (with 
  261. minor modifications) as input for RPLCOMP.EXE. 
  262.  
  263. While ->RPL is compiling a string, it recognizes certain words and generates 
  264. appropriate code for them. All other words are assumed to be the labels of 
  265. objects in the runstream and are emitted simply as 5-nibble constants - the 
  266. reference table (see below) and the assembler symbol table are searched to 
  267. resolve the appropriate 5-nibble addresses. If an entry can't be found in one 
  268. of the tables and its 1st chararcter is a 'x', then ->RPL will try to resolve 
  269. the word without the leading 'x' as a built-in word (e.g. for 'xDROP' the 
  270. address #1FBD8 would be generated). 
  271.  
  272. If the currently processed token isn't resolvable by ->RPL as an object, 
  273. entry, or built-in word, it is passed to the user-RPL compiler, palparse. 
  274. If the result is an ID or prg, an error will be generated. If the token is 
  275. parsed to a %, it will be converted to a # (eg. "12345" ->RPL --> <3039h> 
  276. (negative values are mapped to 0 and fractional parts are ignored)); any 
  277. other valid object is simply added to the runstream (eg. [[1,2][3,4]] (F(.)) 
  278. inserts a 2*2 array of %). 
  279.  
  280. The following words are recognized by ->RPL or generated by RPL->: 
  281.  
  282. LAM <id>                                (1) 
  283.     DOLAM object whose name is specified by <id>. 
  284.  
  285. ID <id>                                 (1) 
  286.     DOIDNT object whose name is specified by <id>. 0-IDs aren't supported by 
  287.     ->RPL. 
  288.  
  289. TAG <id> <ob> 
  290.     DOTAG object whose tag is specified by <id> and whose object is given 
  291.     by <ob>. 
  292.  
  293. $ "string"                              (1) 
  294.     DOCSTR object with the contents contained between the quotes. 
  295.  
  296. CHR <char>                              (1) 
  297.     DOCHAR object with the specified character. 
  298.  
  299. # <hex>                    (3) 
  300. #<hex>                    (3) 
  301.     DOBINT object whose body is the number specified in hex. 
  302.  
  303. % <real> 
  304.     DOREAL object with the specified floating-point number. 
  305.  
  306. %% <extended real> 
  307.     DOEREL object with the specified floating-point number. The number is 
  308.     parsed with % resolution. 
  309.  
  310. C% <real> <real> 
  311.     DOCMP object with the specified floating-point numbers. 
  312.  
  313. C%% <extended real> <extended real> 
  314.     DOECMP object with the specified floating-point numbers. The numbers are 
  315.     parsed with % resolution. 
  316.  
  317. PTR <address in hex>            (2,5) 
  318.     Inserts the specified address as a runstream pointer-obj. 
  319.  
  320. ROMPTR <LID> <rom word> 
  321.     DOROMP obj whose body will contain the two 3-digit hex numbers. 
  322.  
  323. HXS <length in hex> <hstring> 
  324. GROB <length in hex> <hstring> 
  325. CODE <length in hex> <hstring>        (2) 
  326. ARRY <length in hex> <hstring>        (2) 
  327. LNKARRY <length in hex> <hstring>    (2) 
  328. LIBRARY <length in hex> <hstring>    (2) 
  329. BACKUP <length in hex> <hstring>    (2) 
  330. LIBDAT <length in hex> <hstring>    (2) 
  331. EXT1 <length in hex> <hstring>        (2,4) 
  332. EXT2 <length in hex> <hstring>        (2) 
  333. EXT3 <length in hex> <hstring>        (2) 
  334. EXT4 <length in hex> <hstring>        (2) 
  335.     Specified object whose body is made from the specified hex-string. 
  336.     Zero-length obj's aren't supported by ->RPL. 
  337.  
  338. ACPTR <data address> <access routine address>    (2,4) 
  339.     DOACPTR object, whose data and access routine addresses are built from 
  340.     the two specified hex numbers. 
  341.  
  342. NIBB <length in hex> <hstring>        (2) 
  343.     Adds the binary form of the specified hex string to the runstream, eg. 
  344.     NIBB 7 84E2000 creates a 0-ID. 
  345.  
  346. CODE <assembler source ..> ENDCODE 
  347.     CODE object, the assembler is called to assemble the body. 
  348.  
  349. ASSEMBLE <assembler source ..> RPL 
  350.     The assembler is called to assemble the inline code. 
  351.  
  352. INCLUDE <name> 
  353.     The accessable path is searched for a variable with the name <name>. Its 
  354.     contents must be a compilable string and may contain further INCLUDE 
  355.     statements. The resulting code is inserted at the position of the INCLUDE 
  356.     statement. 
  357.  
  358. INCLOB <name>                (2) 
  359.     The accessable path is searched for a variable with the name <name>. Its 
  360.     recalled contents are inserted at the position of the INCLOB statement. 
  361.  
  362.  
  363. The following words create runstream pointer obj's: 
  364.  
  365. UNIT    DOEXT  - Unit start 
  366. SYMBOL    02AB8  - Symbolic start 
  367. ::    DOCOL  - Program start 
  368. {    DOLIST - List start 
  369. }    SEMI   - List terminator 
  370. ;    SEMI   - Program, UNIT or SYMBOL terminator 
  371.  
  372.  
  373. Text surrounded by ' (' and ') ' is ignored by ->RPL. 
  374.  
  375.  
  376. Before you start compiling your own objects, play with the decompiler to 
  377. get some examples of the syntax definitions, eg. try { + } 1 GET RPL-> to 
  378. decompile 'x+'. 
  379.  
  380. ->RPL will automatically add SEMIs at the end of a compiled object to close 
  381. any open composite object, ie. compiling ":: 1" will create :: ONE ; 
  382.  
  383. Note (1) 
  384.     Character substitution is supported via '\xxx' in strings, IDs, LAMs and 
  385.     CHRs using the internal routine which does the tranlsation for TRANSIO, 
  386.     code 3 (see the '48 manual for a complete description). You must use 
  387.     '\034' to insert doublequotes (") into strings. 
  388.     RPL-> generates (") within strings, not \034. 
  389.  
  390. Note (2) 
  391.     These statements are not supported by RPLCOMP.EXE. 
  392.  
  393. Note (3) 
  394.     ->RPL accepts BINTS in one of the following form: 
  395.     # xxx - allways compiled to BINT objects 
  396.     #xxx  - searches the ROM for a BINT with the appropriate value, if 
  397.         found a pointer to it is generated instead of a BINT object 
  398.     xxx   - real numbers are COERCED and then handled like #xxx 
  399.  
  400. Note (4) 
  401.     ACPTR and EXT1 obj's do have the same prologue addresses but are defined 
  402.     differently, the former is a GX only obj, the latter an SX only obj. 
  403.     ->RPL won't allow you to compile a EXT1 obj on a GX and vice versa. RPL-> 
  404.     can only handle ACPTR ! 
  405.  
  406. Note (5) 
  407.     If you want to recompile a source generated by RPL->, you must manually 
  408.     replace all PTR 12345 statements by 
  409.  
  410.         ASSEMBLE 
  411.             CON(5)    #12345 
  412.         RPL 
  413.  
  414.  
  415. 2.3 The Saturn Assembler/Disassembler 
  416. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  417.  
  418. The assembler defines a subset of SASM.EXE written by Nathan Zelle. You can 
  419. use it 'stand-alone' or in conjunction with the RPL compiler ->RPL. It's a 
  420. 2-pass assembler. 
  421.  
  422. The input string should be plain ASCII (with blanks and/or TAB's) generated 
  423. on a PC or the '48 itself. 
  424.  
  425. It is 'free format' which means that no column counting is required, except 
  426. that labels MUST begin in the first coloumn of a line. 
  427.  
  428. If a line consists only of a comment, an '*' MUST be in column 1. Empty lines 
  429. are ignored. 
  430.  
  431. The general line structure is: "<label> [<mnemonic> [<parameter>] [<comment>]]" 
  432. or "* <comment>"; the fields are seperated by blanks or TABs. 
  433.  
  434. Most parameters can be symbolic (eg. " GOVLNG (=SAVPTR)+45*3" is valid). 
  435.  
  436. The assembler supports conditional assembling as well as defining equates via 
  437. "Label  EQU  expression". Please refer to SASM.DOC for more details. 
  438.  
  439. You can call global entry points if a reference table is installed. 
  440.  
  441. A predefined standard macro named LOOP is also included. If entered in the 
  442. mnemonic field it will be assembled to " GOVLNG  =Loop", an address which 
  443. simply does 
  444.  
  445. =Loop A=DAT0  A 
  446.       D0=D0+  5 
  447.       PC=(A) 
  448.  
  449. If the assembler source don't contain any code, the 2nd pass is skiped to 
  450. speed up RPL define like constructs - eg. a directory may hold along with 
  451. the source strings a variable HEADER: 
  452.  
  453. (HEADER) 
  454. ASSEMBLE 
  455. @a EQU =1GETLAM 
  456. !a EQU =1PUTLAM 
  457. @b EQU =2GETLAM 
  458. !b EQU =2GETLAM 
  459. nr EQU =TWO 
  460. RPL 
  461.  
  462. which may be included by a source like: 
  463.  
  464. (xyz - just a program) 
  465. INCLUDE HEADER 
  466. :: 
  467.   CKN 
  468.   DUP nr #<> case SETSIZEERR 
  469.  
  470.   ' NULLLAM nr NDUPN {}N BIND 
  471.  
  472.   @a @b 2DUP EQUAL ?SWAP 
  473.   !b !a 
  474.     (...etc...) 
  475.   ABND 
  476. ; 
  477.  
  478.  
  479. 2.3.1 The Assembler Parameter Field Parser 
  480. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  481.  
  482. Parameter fields are parsed by an expression parser that is defined as 
  483. follows: 
  484.  
  485.     expr : expr op1 term | term 
  486.     term : term op2 fact | fact 
  487.     fact : '(' expr ')' | op3 fact | '(' '=' entry ')' | '(' symbol ')' | num 
  488.  
  489.     op1  : '+' | '-' | '!' | '|' | '^' 
  490.     op2  : '*' | '/' | ':' 
  491.     op3  : '-' | '"' 
  492.  
  493.     num  : real-number | '#' hxs-number 
  494.  
  495.     entry  : label of RPL.TAB 
  496.     symbol : label of the assembler symbol table 
  497.  
  498.     op  action 
  499.     ÄÄ  ÄÄÄÄÄÄ 
  500.     *   multiply 
  501.     /   divide 
  502.     :   modulo 
  503.     "   ones complement 
  504.     -   subtract / twos complement 
  505.     +   add 
  506.     !   bit AND 
  507.     |   bit OR 
  508.     ^   bit XOR 
  509.  
  510. A complete expr must not contain whitespace chars. If an expression consists 
  511. only of a '#' number, an entry or a symbol, the parenteses aren't neccessary 
  512. (eg. @n EQU =1GETLAM ). Real numbers are converted internally to HXS numbers, 
  513. the accuracy is 64 bit. Parsing real numbers and hex numbers is done by the 
  514. '48 internal real/hex parser. The expr/term/fact parser uses the solver 
  515. token type table. 
  516.  
  517. Expressions of EQU parameter fields must resolve to the requested number 
  518. during the 1st assembler pass; they are ignored in the 2nd pass. 
  519.  
  520.  
  521. 2.4 The Reference Table 
  522. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  523.  
  524. RPL->, ->RPL, COD->, ->COD, EC, E<->A and 4/5/7 are looking for a reference 
  525. table named RPL.TAB which is used to resolve names and addresses of ROM 
  526. entry points. It may be stored in a variable, as a backup object in any port 
  527. or as a library command. If RPL.TAB exists, its recalled contents will be 
  528. evaluated and if the result is a string starting with '\000\010' it will be 
  529. used as a reference table. It is recommended to use one of the two tables 
  530. shipped with RPL48; they are made using the latest entries lists released by 
  531. HP as database - double named entries are removed and a few user-RPL names 
  532. are added to avoid conflicts when de/compiling different '->', '>>', 'END' 
  533. (user-RPL) words. 
  534.  
  535. For generating your own tables, use GENTAB.C, also shipped with RPL48. 
  536.  
  537. The following example (HP terminology) outlines the structure of a reference 
  538. table: 
  539.  
  540. ASSEMBLE 
  541.     CON(5)  =DOCSTR        String prologue 
  542.     REL(5)  TabEnd          Length field 
  543.     NIBASC  '\00\n'        Reference table identifier 
  544. *                A hash table, for each char from ' ' - DEL 
  545. *                a 5-nib offset into the table 
  546.     CON(5)    0        ' ' entry, empty 
  547.     REL(5)    _!_        relativ offset to words starting with '!' 
  548.     CON(5)    0        '"' entry, empty 
  549. *       ...            '#' - 'C' 
  550.     REL(5)    _D_        'D' entry 
  551. *       ...            'E' - '}' 
  552.     CON(5)    0        '~' entry, empty 
  553.     CON(5)    TabEnd        DEL entry, always TabEnd 
  554.  
  555. _!_ 
  556.     CON(6)    #9623A0 
  557.     NIBASC    `!!append$` 
  558. *    ... 
  559. _D_ 
  560. *                úÄÄÄÄÄÄÄ Length of the label in bytes. 
  561. *                3        A label can't be > 15 chars in size. 
  562. *                3úââââÄÄ Address associated to the label, here 074E4 
  563. *                333333 
  564.     CON(6)  #6074E4        Address/length field of the following 
  565.     NIBASC  'DOBIND'    Label 
  566.  
  567. TabEnd 
  568. RPL 
  569.  
  570.  
  571. 2.5 Command Reference 
  572. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  573.  
  574. RPL->        ( ob            --> $                ) 
  575.  
  576.     Decompiles an object into a string. The string can be used as input for 
  577.     ->RPL without modifications (most times). 
  578.  
  579.  
  580. ->RPL        ( $            --> ob                ) 
  581.  
  582.     Compiles the input string to an object. 
  583.  
  584.  
  585. DCADR        ( hxs[adr]        --> $ hxs[adr]'            ) 
  586.  
  587.     Decompiles the object referenced by the address adr to a string in 
  588.     level 2 and increment the address by the object size. 
  589.  
  590.  
  591. COD->        ( code            --> $                ) 
  592.  
  593.     Disassembles a code object, generates HP styled mnemonics. The reference 
  594.     table is searched for addresses of GO and Dx=(5) mnemonics. The string 
  595.     can be used as input for ->COD without modifications (most times). 
  596.  
  597.  
  598. ->COD        ( $            --> code LibDat            ) 
  599.  
  600.     Assembles a code object. LibDat is the compressed form of a cross 
  601.     reference listing, use SYM-> (see below) for decompression. 
  602.  
  603.  
  604. ->OB        ( hxs[adr]        --> ob                ) 
  605.         ( #adr            --> ob                ) 
  606.         ( XLIB            --> ob                ) 
  607.         ( ob            --> ob'                ) 
  608.  
  609.     Input    Action 
  610.     ÄÄÄÄÄ       ÄÄÄÄÄÄ 
  611.     hxs        Build a pointer, pointing to the address given by the value 
  612.         of hxs[adr]. 
  613.     #        Same as for hxs, except if the value of # points to a valid 
  614.         ob in the hidden ROM; in this case the object is copied into 
  615.         TEMPOB. Eg. "# 72000" ->RPL ->OB returns the message table 
  616.         of the internal library 0. 
  617.         On a GX, passing a # is the same as passing a HXS. 
  618.     XLIB    Does a rompointer recall. 
  619.     ob        Unconditionally TOTEMPOB. 
  620.  
  621.  
  622. DAN        ( hxs[adr] %n        --> $1 .. $n hxs[adr]'        ) 
  623.  
  624.     Disassembles n instructions starting at address hxs[adr]. 
  625.  
  626.  
  627. DA1        ( hxs[adr]        --> $ hxs[adr]'            ) 
  628.  
  629.     Disassembles the instruction at address hxs[adr]. 
  630.  
  631.  
  632. DAXY        ( hxs[start] hxs[end]    --> $                ) 
  633.  
  634.     Disassembles until the actual adr. is > hxs[end], starting at address 
  635.     hxs[start]. 
  636.  
  637.  
  638. SYM->        ( LibDat        --> $                ) 
  639.  
  640.     Converts the cross reference table produced by ->COD into a string. 
  641.  
  642.  
  643. $->        ( $            --> ob                ) 
  644.  
  645.     Converts a hex-dump to an object. 
  646.  
  647.  
  648. ->$        ( ob            --> $                ) 
  649.  
  650.     Generates a hex-dump of an object. 
  651.  
  652.  
  653. EC        (            --> ?                ) 
  654.  
  655.     Entries Catalog - the reference table browser. Errors if no RPL.TAB 
  656.     can be found. 
  657.  
  658.     When starting EC the first time, it'll create the variable ECpar in 
  659.     the HOME directory. It contains a HXS that is used by EC as a lookup 
  660.     table into RPL.TAB; you may store the variable into a port (like 
  661.     RPL.TAB). Any time you install a new reference table it is neccessary 
  662.     to purge ECpar ! 
  663.  
  664.     The main display of EC shows eight entries, one per line. Each line shows 
  665.     the name and the addresses of an entry, a 'm' behind the address marks non 
  666.     RPL entries (ie. ML entries). These words are probably for use within 
  667.     assembly only. One line is inversed, showing the current position of 
  668.     the cursor bar which can be moved by the UP/DOWN arrows. 
  669.  
  670.     Active keys in the main display of EC: 
  671.  
  672.       Unshifted: 
  673.     UP    - move scroll bar up one word 
  674.     DOWN  - move scroll bar down one word 
  675.     ENTER - push highlighted word as $ onto the stack. If EC is launched 
  676.         from a command/edit line, ENTER coppies the word into the 
  677.         editline starting at the current cursor position 
  678.     NXT   - scan for next occurence of the SCAN word. 
  679.     ON    - exit EC or cancel sub-action 
  680.  
  681.       Rightshifted: 
  682.     ENTER - in case no editline exists, the current word is copied into a 
  683.         newly opened editline 
  684.     UP    - move to first entry 
  685.     ON    - turn off 
  686.  
  687.       Menu keys: 
  688.     PG|^  - page up 
  689.     PG|v  - page down 
  690.     SCAN  - prompts for a $ to search, ENTER starts searching. If EC is 
  691.         launched from a command/edit line, the prompt looks a bit 
  692.         suspicious, but its functionality is the same 
  693.     A-Z   - try it 
  694.     A->ST - push the address of the current word onto the stack. If EC 
  695.         is launched from a command/edit line, the A->ST key changes 
  696.         to the ABOUT key. 
  697.     HELP  - provides two pages of help on keys 
  698.  
  699.     For use of EC within a normal edit line, append the following list to 
  700.     your CST variable and launch EC with CST EC: 
  701.     { $ "EC" :: TakeOver ROMPTR 4D2 C (EC) ; } 
  702.  
  703.  
  704. E<->A        ( hxs[adr] | $name    --> $name | hxs[adr]        ) 
  705.  
  706.     Searches the reference table for a name or address of a given address or 
  707.     name. Errors if the label or address can't be resolved. 
  708.  
  709.  
  710. RPLtab        (            --> $                ) 
  711.  
  712.     Tries to recall the ref. table via RPL.TAB. If no table is found, a 
  713.     zero-length string is returned. 
  714.  
  715.  
  716. 4/5/7        (            -->                ) 
  717.  
  718.     Starts the medium font sys-stack display in five line mode. Pressing 
  719.     4/5/7 in five line mode switches to seven line mode, in seven line mode 
  720.     the sys-stack is canceled. 
  721.  
  722.     If you have flag 61 set, the commandline changes to sys-RPL mode, and 
  723.     the i-stack allows you to edit objects in sys-RPL syntax when pressing 
  724.     the EDIT menu key. 
  725.  
  726.     The following keys are redefined while the 5/7 stack is active: 
  727.       - pressing the up arrow without an active edit/commandline starts a 
  728.     5/7 level interactive sys-RPL stack 
  729.       - pressing the down arrow without an active edit/commandline starts 
  730.     editing the object of stack level one in sys-RPL syntax, if flag 
  731.     61 is set. 
  732.       - pressing ENTER to terminate a command line compiles it using the 
  733.     internal ->RPL, if flag 61 is set. 
  734.  
  735.     YOU MUST NOT MOVE THE <-RPL-> LIBRARY WHILE 4/5/7 IS ACTIVE !! 
  736.     (ie. DON'T MERGE THE PORT WHERE <-RPL-> IS STORED WITH AN ACTIVE 4/5/7 !!) 
  737.  
  738.     Clear flag 62 to quit 4/5/7 if you wan't to purge/move <-RPL->. 
  739.  
  740.  
  741. CC        (            --> ?                ) 
  742.  
  743.     Character set Catalog. CC displays a map of 128 characters in the small 
  744.     font along with some more information for the highlighted char. You can 
  745.     move through the map using the cursor keys. If you hold down one of the 
  746.     cursor keys, it will repeat until you release. The ON-key exits the 
  747.     program, RIGHT-ON turns the calc off and ENTER fetches the char number 
  748.     (tagged with the char) to the stack. 
  749.  
  750.     There are three menu keys available: 
  751.       SWAP - swaps between the upper/lower half of the char set 
  752.       BIN  - toggles the char code display from real/hex to binary and back 
  753.       EXIT - leaves CC 
  754.  
  755.     If you launch CC within an active editline (eg. via the CST menu), ENTER 
  756.     will copy the highlighted character into the editline to the current 
  757.     cursor position. For use of CC within a normal edit line, append the 
  758.     following list to your CST variable and launch CC with CST CC: 
  759.     { $ "CC" :: TakeOver ROMPTR 4D2 10 (CC) ; } 
  760.  
  761.  
  762. 2.7 Hooks 
  763. ÄÄÄÄÄÄÄÄÄ 
  764.  
  765. There are a few user hooks in <-RPL->, each an unnamed ROMPTR: 
  766.  
  767. ROMPTR 4D2 13    (            -->                ) 
  768.  
  769.     Switches to ADISP and displays a 5/7 level sys-RPL stack. 
  770.  
  771.  
  772. ROMPTR 4D2 14    (            -->                ) 
  773.  
  774.     Errors if <-RPL-> isn't ATTACHed to the HOME directory. 
  775.  
  776.  
  777. ROMPTR 4D2 15    ( ob            --> $                ) 
  778.  
  779.     Decompiles an object in quiet mode, eg. for editing. 
  780.  
  781.  
  782. ROMPTR 4D2 16    ( $            -->                ) 
  783.  
  784.     Compiles a string in quiet mode, eg. after editing. 
  785.  
  786.  
  787. Note: no stack checks are done by these routines ! 
  788.  
  789.  
  790. 2.7 Things to Notice 
  791. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  792.  
  793. ->RPL maintains a global assembler symbol table while compiling an object, 
  794. ie. it is possible to jump backward from a code object to a previous one: 
  795.  
  796. :: 
  797.   CODE 
  798. Lp LOOP 
  799.   ENDCODE 
  800.   CODE 
  801.    GOTO lp 
  802.   ENDCODE 
  803. ; 
  804.  
  805. (Note: in the current version of <-RPL-> this seems not to work, I'm bug 
  806.  hunting... Detlef) 
  807.  
  808. ->RPL tries to resolve a token in the following order: 
  809.     1. check for atomic object (eg. %, # et c.) 
  810.     2. search reference table 
  811.     3. search symbol table 
  812.     4. check for #<hex-no> 
  813.     5. check for user-RPL word 
  814.     6. check for user-RPL object 
  815.  
  816. The search of the symbol table enables the programmer to use DEFINE like 
  817. constructs: 
  818.  
  819. :: 
  820.   ASSEMBLE 
  821. @val EQU =1GETLAM 
  822. !val EQU =1PUTLAM 
  823.   RPL 
  824.  
  825.   ONE 1LAMBIND 
  826.   @val #1+ !val 
  827.   1GETABND 
  828. ; 
  829.  
  830.  
  831. 3. <-LIB-> 
  832. íííííííííí 
  833.  
  834.  
  835. 3.1 Overview 
  836. ÄÄÄÄÄÄÄÄÄÄÄÄ 
  837.  
  838. <-LIB-> contains 39 commands, including a library maker (D->LIB), a library 
  839. splitter (L->DIR), commands to handle any sort of composite objects and 
  840. commands to manage libraries. 
  841.  
  842. Libraries are very useful objects to extend the command set of a '48 in a 
  843. 'native' manner, but unfortunately library creation is not supported by the 
  844. '48 firmware. The HP tools package contains the program USRLIB.EXE, which 
  845. provides library creation on a PC; if you want to move your most often used 
  846. programs into a library (because of easier handling and to keep your VARs 
  847. area clean), you have to collect them into a subdirectory, add a few control 
  848. variables, transfer the directory in binary form to a PC, run USRLIB.EXE on 
  849. it, and transfer the created library back to your '48, where you can install 
  850. and test the library. 
  851.  
  852. <-LIB-> provides the command D->LIB that works on the currently active 
  853. directory, allowing you to create a library from this directory on the '48 
  854. itself - no transfers, no PC, and no USRLIB.EXE are required. 
  855.  
  856. The input directory stucture of D->LIB is very similar to the directory 
  857. structure required by USRLIB.EXE, thus existing USRLIB.EXE input can be 
  858. used for a library creation with minor changes (the difference is the 
  859. format of the $MESSAGE control variable, see below). 
  860.  
  861.  
  862. 3.2 Control Variables 
  863. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  864.  
  865. The library creation process is controlled by some variables with reserved 
  866. names and only the current directory is searched for their presence (note: 
  867. multiple occurences of these names are ignored, only the contents of the 
  868. first one found in the current directory is used for the library creation 
  869. process): 
  870.  
  871. $ROMID 
  872.     Must contain a real or binary number representing the LID that is to 
  873.     be given to the library. The LID must be in the range 0..2047. Negative 
  874.     real numbers are mapped to 0. 
  875.     This is the only control variable that MUST exist in the current 
  876.     directory ! 
  877.  
  878. $TITLE 
  879.     Should contain a character string to be used as the name of the library 
  880.     (note: any other object is converted to a string). The first few 
  881.     characters of the name are displayed in the LIBRARY menu label 
  882.     associated to the library, the first 22 characters are displayed by 
  883.     pressing REVIEW in the LIBRARY menu. If $TITLE is absent or contains an 
  884.     empty string, no title is generated and the resulting library doesn't 
  885.     have a menu label in the LIBRARY menu (note: you can switch to the 
  886.     library's command menu by executing %LID MENU, even if the library 
  887.     doesn't have a name or is not attached). 
  888.  
  889. $CONFIG 
  890.     Must contain a program to be executed at configuration time. 
  891.     The configuration code can generally NOT be written in user-RPL, but 
  892.     simple programs such as \<< 123 ATTACH \>> are Ok - more complicated 
  893.     programs should take care to leave the stack unchanged, and be sure 
  894.     NOT TO ERROR ! An error in a configuration program will cause a warmstart; 
  895.     the configuration code is called again during the startup process, 
  896.     producing a new error etc. If you are accidentally trapped by this, you 
  897.     must clear your memory to remove the faulty library ! 
  898.  
  899. $MESSAGE 
  900.     Must contain a list of strings to be combined into a message table (note: 
  901.     any other objects are converted to strings). The message numbers 
  902.     correspond to the list positions. In user-RPL you can generate errors 
  903.     with your own messages in the following manner: 
  904.         #32001h DOERR 
  905.              33333 
  906.              333àáÄÄ Message number     (here 1) 
  907.              àááÄÄÄÄ LID                (here #320h = 800) 
  908.     In sys-RPL you can use 
  909.         # 32001 ERROROUT 
  910.  
  911.     In this example an error is generated, using the first message from the 
  912.     message table of a library with the LID 800. 
  913.  
  914.     Note: The message list structure is NOT compatible to USRLIB.EXE. 
  915.  
  916. $VISIBLE 
  917.     Must contain a list of names of variables to be converted to user- 
  918.     accessible, named library commands. By default, all variables will be 
  919.     translated to named library commands. When the $VISIBLE list is present, 
  920.     only the names in this list are included in the library hash table. An 
  921.     empty list is Ok, meaning that no hash table is generated. 
  922.  
  923. $HIDDEN 
  924.     Must contain a list of names of variables that are to be converted to 
  925.     unnamed objects in the library. When the $HIDDEN list is present, those 
  926.     names listed are not entered in the library hash table. If both $VISIBLE 
  927.     and $HIDDEN are present, only $HIDDEN will be used. 
  928.  
  929.     Note: all visible commands appear as labeled softkeys in the menu 
  930.     associated to the library, all hidden commands are not, and there is no 
  931.     way to access them from user scope. 
  932.  
  933. $VARS 
  934.     Must contain a list of variables that should remain RAM-based - i.e. the 
  935.     objects of the variables listed in $VARS are not included in the library 
  936.     and no XLIB pointers are made to substitute their names. All other 
  937.     variables of the current directory are included in the library. 
  938.  
  939.     Note: You should add all subdirectory names of the current directory to 
  940.     the list. 
  941.  
  942. $ROMID must exist in the current directory, all other control variables are 
  943. optional - eg. you can generate libraries containing only a configuration 
  944. program or a message table. All control variables are internally handled by 
  945. D->LIB to be $VARS and can't be accessed from within the library commands. 
  946.  
  947.  
  948. 3.4 Command Reference 
  949. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  950.  
  951. D->LIB        (            --> lib                ) 
  952.  
  953.     Dir to lib; assembles a library from the objects of the current directory. 
  954.     The creation process is controlled by a few variables with reserved names 
  955.     (see '3.3 Control Variables'). 
  956.     If you set flag -13 before running D->LIB, it will switch off the screen 
  957.     while working (for saving time and batteries). 
  958.  
  959.  
  960. L->DIR        ( %LID            --> dir                ) 
  961.         ( xlib            --> ob                ) 
  962.  
  963.     Lib to dir; if the argument is a LID then L->DIR assembles a directory 
  964.     containing all commands of this library as variables. The neccessary 
  965.     control variables (see 3.3) are also generated. D->LIB may be used to 
  966.     recreate the library. 
  967.     If the argument is an XLIB, then L->DIR recalls its object from the 
  968.     associated library onto the stack. 
  969.     If you set flag -13 before running L->DIR on a library, it will switch 
  970.     off the screen while working. 
  971.  
  972.     Note: You cannot use L->DIR to split <-LIB->, this should prevent users 
  973.     from a memory lost. If you are familiar with the internals of your '48, 
  974.     use 'ROMPTR@' (or ->OB of <-RPL->) to extract single routines from 
  975.     <-LIB->, but beware of starting the routines in RAM, most of them will 
  976.     crash your calc when running alone ! 
  977.  
  978.  
  979. MCFG        (            -->                ) 
  980.  
  981.     Make config; stores a configuration program into a variable named 
  982.     '$CONFIG' into the current directory. This configuration program will 
  983.     attach the generated library to the home directory at warmstarts (ON-C 
  984.     etc.). 
  985.     '$ROMID' must exist in the current directory. 
  986.  
  987.  
  988. ML->D        (            --> prg                ) 
  989.  
  990.     Generates a program with the following interface: 
  991.  
  992.         ( {}            --> libdta            ) 
  993.  
  994.     The list can contain anything. The program checks for argument count and 
  995.     type and may error with: 
  996.     #201 - To Few Arguments  - nothing on the stack 
  997.     #202 - Bad Argument Type - not a list on the stack 
  998.  
  999.     '$ROMID' must exist in the current directory. 
  1000.  
  1001.  
  1002. MD->L        (            --> prg                ) 
  1003.  
  1004.     Generates a program with the following interface: 
  1005.  
  1006.         ( libdta        --> {}                ) 
  1007.  
  1008.     The program checks for argument count, type and correct LID and may error 
  1009.     with: 
  1010.     #201 - To Few Arguments   - nothing on the stack 
  1011.     #202 - Bad Argument Type  - no library data on the stack 
  1012.     #203 - Bad Argument Value - the libdta wasn't created by this lib 
  1013.  
  1014.     '$ROMID' must exist in the current directory. 
  1015.  
  1016.   Note: Store the programs generated by ML->D and MD->L into variables in 
  1017.   your source directory and use them as an interface to generate/resolve 
  1018.   data associated to the resulting library. 
  1019.  
  1020.  
  1021. OB->        ( prg            --> ob1 .. obn %n        ) 
  1022.         ( xlib            --> %LID %objno            ) 
  1023.         ( arry            --> ob1 .. obn { %di .. %d1 }    ) 
  1024.         ( alg            --> ob1 .. obn %n        ) 
  1025.         ( dir            --> ob1 id .. obn id %n        ) 
  1026.         ( id            --> $                ) 
  1027.         ( libdta        --> {} %LID            ) 
  1028.         ( bak            --> ob id            ) 
  1029.         ( id            --> $                ) 
  1030.         ( ob            --> dispatch to OBJ->        ) 
  1031.  
  1032.     OB-> is an extension to the built-in OBJ->, supporting system level 
  1033.     objects. 
  1034.  
  1035.  
  1036. ->DIR        ( ob1 id1 .. obn idn %n    --> dir                ) 
  1037. ->PRG        ( ob1 .. obn %n        --> prg                ) 
  1038. ->XLIB        ( %LID %cmdno        --> xlib            ) 
  1039.         ( #LID #cmdno        --> xlib            ) 
  1040. ->ARR        ( ob1 .. obn %n        --> arry            ) 
  1041.         ( ob1 .. obn { %di .. %d1 } --> arry            ) 
  1042. ->ALG        ( ob1 .. obn %n        --> prg                ) 
  1043. ->LD        ( {} %LID        --> libdta            ) 
  1044. ->BAK        ( ob id            --> bak                ) 
  1045. ->ID        ( $            --> id                ) 
  1046.  
  1047.     Functions to reverse OB->. 
  1048.  
  1049.     About ->ARR: 
  1050.        Generates arrays of any type and any dimension (eg. a four dimensional 
  1051.        array of libraries :-). 
  1052.        %di * .. * %d1 must be = n, ob1 .. obn must be of the same type. 
  1053.        All possible parameter errors are trapped. 
  1054.  
  1055.  
  1056. ADRp        ( ob            --> ob #addr            ) 
  1057.  
  1058.     Get address of ob. 
  1059.  
  1060.     Note: The data stack is a stack of pointers to objects. ADRp simply 
  1061.     returns the value from the top element (about the 'p', see 'LIBp' below). 
  1062.  
  1063.  
  1064. $romid 
  1065. $visible 
  1066. $title 
  1067. $config 
  1068. $vars 
  1069. $hidden 
  1070. $message    (            --> '$XXX'            ) 
  1071.  
  1072.     These commands just put a control variable name onto the stack. 
  1073.  
  1074.  
  1075. LBCRC        ( lib            --> lib'            ) 
  1076.         ( bak            --> bak'            ) 
  1077.  
  1078.     Recalculates the CRC of a library or backup, useful if you have patched 
  1079.     it because modifying the body of a library or backup invalidates the CRC 
  1080.     included at the end of the body. 
  1081.  
  1082.  
  1083. RNLIB        ( lib $            --> lib'            ) 
  1084.  
  1085.     Renames a library, ie. changes title. 
  1086.  
  1087.  
  1088. CHLID        ( lib %            --> lib'            ) 
  1089.  
  1090.     Change LID; this program allows you to change the LID of a library if 
  1091.     it's not splittable. 
  1092.  
  1093.     Note: Most time a LID is also hardcoded in the config code - this can 
  1094.     generally not be changed by CHLID. You have to attach the library manually 
  1095.     after a warmstart. Also any library has its LID coded in a field above 
  1096.     any visible command (the error handling system identifies the command 
  1097.     that caused an error using this field (the sys-RPL commands 'CKn' copies 
  1098.     this values to the appropriate location)). These fields are not changed 
  1099.     by CHLID (yet). 
  1100.  
  1101.  
  1102. RHASH        ( %LID            --> hxs                ) 
  1103.  
  1104.     Recall hash table; get a pointer to the hash table of a library. 
  1105.  
  1106.  
  1107. RLINK        ( %LID            --> hxs                ) 
  1108.  
  1109.     Recall link table; get a pointer to the link table of a library. 
  1110.  
  1111.  
  1112. RCFG        ( %LID            --> ob                ) 
  1113.  
  1114.     Recall config code; get a pointer to the config code of a library. 
  1115.  
  1116.  
  1117. RMSG        ( %LID            --> arry            ) 
  1118.  
  1119.     Recall message table; get a pointer to the message table of a library. 
  1120.  
  1121. RTITLE        ( %LID            --> $                ) 
  1122.  
  1123.     Recall title; get the name of a library. 
  1124.  
  1125.  
  1126.     Note: RHASH, RLINK, RCFG, RMSG and RTITLE don't error if the library 
  1127.     associated to %LID didn't contain the requested item, they leave the 
  1128.     stack unchanged in that case. 
  1129.  
  1130.  
  1131. RPORT        ( %port            --> ob1 .. obn            ) 
  1132.  
  1133.     Recalls pointers to all objects of a given port (0/1/2 - 3-33 on a GX) 
  1134.     onto the stack, ignoring the R/W status of that port. 
  1135.  
  1136.  
  1137. RLIB        ( :%port:%LID        --> lib                ) 
  1138.         ( %LID            --> libn %portn ...        ) 
  1139.  
  1140.     Recall lib; the 1st case recalls a library from a given port, the 2nd 
  1141.     case searches ports 0,1,2 (followed by ports 3-33 on a GX) for libraries 
  1142.     with %LID, returning all found libraries and the port numbers where 
  1143.     they're stored. 
  1144.  
  1145.     Note: On a SX this command actually returns pointer to libraries (like 
  1146.     RPORT), if you recall a lib and try to purge it while it's on the stack, 
  1147.     you'll get a 'Object in use' error. Execute NEWOB or store it into a 
  1148.     variable first. 
  1149.  
  1150.  
  1151. PGLIB        ( :%port:%LID        -->                ) 
  1152.         ( %LID            -->                ) 
  1153.  
  1154.     Purge lib; the 1st case works like :%port:%LID PURGE, in the 2nd case the 
  1155.     ports are searched in order 0,1,2 (followed by ports 3-33 on a GX) for an 
  1156.     active library with %LID. The difference to PURGE: if the library is 
  1157.     attached to the home directory, it's detached before purging. On a SX: 
  1158.     Also if there is an inactive library with the same LID in any other port, 
  1159.     it becomes active and is attached to the HOME directory (if flag 5 is 
  1160.     set, its config code is executed - see STLIB below). 
  1161.  
  1162.  
  1163. STLIB        ( lib %port        -->                ) 
  1164.  
  1165.     Store lib into port; there're a few differences to STO: 
  1166.     - The library is installed full; a warmstart isn't neccessary 
  1167.       and thus not initiated at the next power cycle. All warmstart 
  1168.       volatile variables (stack, PICT) remains intact. 
  1169.     - The library last stored is visible to the '48 (in case of 
  1170.       having a library with the same LID installed in another port). 
  1171.     - If flag 5 is clear, the library is attached simply to the 
  1172.       home directory. 
  1173.     - If flag 5 is set, the config code of the library is executed 
  1174.       under warmstart conditions. Usefull for testing a config code. 
  1175.  
  1176.     Note: This command is currently disabled on a GX ! 
  1177.  
  1178.  
  1179. ACLIB        ( :%port:%LID        -->                ) 
  1180.  
  1181.     Activate library. You can install libraries with the same LID in different 
  1182.     ports, but only one will be visible to the '48 at the time. During 
  1183.     warmstarts the ports are searched in order 2,1,0 (most cases), ie. the 
  1184.     library stored in the port with the highest number will be active. 
  1185.     ACLIB allows you to switch to any other library with the same LID at 
  1186.     runtime, the effect is immidiate. ACLIB 1st detaches the LID from HOME, 
  1187.     sets the new priority and than a) attaches the LID to HOME again if flag 
  1188.     5 is clear, or b) runs the library config code if flag 5 is set (see STLIB 
  1189.     above). 
  1190.  
  1191.     Note: This command is currently disabled on a GX ! 
  1192.  
  1193.  
  1194. LIBp        ( %LID            --> $                ) 
  1195.  
  1196.     Returns a detailed layout of a library. The map starts with the title (if 
  1197.     exist), followed by the 1st and last address of the lib and the LID. The 
  1198.     remainder lists the contents of the lib, one line of information for each 
  1199.     XLIB entry. Structure of a line: 
  1200.  
  1201.     1st last  xn name  typ 
  1202.         333 3333  33 3333  àááÄ Type of the object 
  1203.         333 3333  33 àáááÄÄÄÄÄÄ Name of the object (if it's a visible cmd) 
  1204.         333 3333  àáÄÄÄÄÄÄÄÄÄÄÄ XLIB number of the object 
  1205.         333 àáááÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Last relative address of the object 
  1206.         àááÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Offset to startaddr. of the object 
  1207.  
  1208.     The list is sorted by offset. Try 1221 LIBp or 2 LIBp. 
  1209.  
  1210.     Note: If you find unexpected 'holes' between two XLIBs (> 10 nibbs) or 
  1211.     XLIBs embedded in other XLIBS, the library wasn't generated using 
  1212.     USRLIB.EXE or D->LIB; do not use D->LIB for recreating it because the 
  1213.     'holes' can hold essential data.. 
  1214.  
  1215.     Note: This command is currently disabled on a GX ! 
  1216.  
  1217.  
  1218. INSTp        (            --> { %LIDn .. %LID1 }        ) 
  1219.  
  1220.     Returns a list of all libraries attached to the current directory, { } if 
  1221.     none. 
  1222.  
  1223.     Note: You can PURGE libraries even if they are attached to a subdirectory. 
  1224.     INSTp can be used to find such zombie references. 
  1225.  
  1226.  
  1227. LIBSp        (            --> { %LID1 .. %LIDn }        ) 
  1228.  
  1229.     Returns a list of all libraries currently installed on your '48. 
  1230.  
  1231.  
  1232.   Note: We didn't use the '?' postfix because normally it marks a routine 
  1233.   for returning a flag in RPL. The JARGON file, v2.9.9, 01 APR 1992 states: 
  1234.  
  1235.     3. The `-P' convention: Turning a word into a question by 
  1236.     appending the syllable `P'; from the LISP convention of appending 
  1237.     the letter `P' to denote a predicate (a boolean-valued function). 
  1238.     The question should expect a yes/no answer, though it needn't. 
  1239.  
  1240.     At dinnertime: 
  1241.        Q: "Foodp?" 
  1242.        A: "Yeah, I'm pretty hungry." or "T!" 
  1243.  
  1244.     At any time: 
  1245.        Q: "State-of-the-world-P?" 
  1246.        A: (Straight) "I'm about to go home." 
  1247.        A: (Humorous) "Yes, the world has a state." 
  1248.  
  1249.   so we used 'p' for marking routines returning information ;-) 
  1250.  
  1251.  
  1252. fEVAL        ( ob            --> ?                ) 
  1253.  
  1254.     Works like EVAL, but switches the display off first. Speeds up evaluation 
  1255.     by ~11%. In case of an error or the ob has finished execution, the 
  1256.     display is switched on again. Not very useful, if ob prompts for input.. 
  1257.  
  1258.  
  1259. 3.5 Things to Notice 
  1260. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  1261.  
  1262. úÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  1263. 3 HP 48 Resource Allocation Guideline: Library ID's 3 
  1264. ~AÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ' 
  1265. 3 0000 - 0256  Take-over libraries; do not use!     3 
  1266. 3 0257 - 0512  HP ROM-based libraries; do not use!  3 
  1267. 3 0513 - 0768  HP RAM-based libraries; do not use!  3 
  1268. 3 0769 - 1791  3rd Party (assigned by HP)           3 
  1269. 3 1792 - 2047  Command-line; do not use!            3 
  1270. àÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  1271.  
  1272. [This sure doesn't seem to leave many for us hackers to use, eh?  -jkh-] 
  1273.  
  1274. *Don't use the following LIDs*, they're handled special by a '48SX (and 
  1275. probably also by a GX): 
  1276.  
  1277. LID        What's special ? 
  1278. ÄÄÄ             ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  1279. 240-255        ROMPTR@ assumes that the associated library command is in the 
  1280.         hidden ROM. 
  1281. 0-256,1792    The central routine to compile IDs (PTR 7BFD on a SX, PTR 
  1282.         7C18 on a GX) returns pointer instead of XLIBs. 
  1283.  
  1284. The library stucture is 'flat', so don't try to include subdirectories in a 
  1285. library, it can end up in a memory lost. 
  1286.  
  1287. Not all program objects that execute correctly from global variables are 
  1288. directly convertable into libraries. Here are some pitfalls: 
  1289.  
  1290.     - Since a library cannot be modified, no library command may be the 
  1291.       target of a STO or PUT operation. 
  1292.     - XLIB names are not usable in all contexts in which global names are 
  1293.       valid arguments. This can cause constructs that reference a named 
  1294.       object to fail. For example, 
  1295.     'A' 5 GETI 
  1296.       where A is a list will not work when A is converted to an XLIB name. 
  1297.       Instead use 
  1298.         A 5 GETI 
  1299.     - XLIB names are not valid as formal variables in algebraics, or as the 
  1300.       independent variable for plotting or solving. 
  1301.     - \->STR applied to a global name that is converted to a 'hidden' library 
  1302.       command (see $HIDDEN) returns a null string. 
  1303.  
  1304. If any visible command starts with the seqence '\<< \->' or '\->' it's marked 
  1305. in the library as a valid command for algebraics. If you press its associated 
  1306. softkey in ALG entry mode, you'll get 'name()'. 
  1307.  
  1308. Multiple occurences of variable names results in an incorrect library because 
  1309. only the contents of the first one is picked up. 
  1310.  
  1311. D->LIB needs ~(1.2 * size_of_source_directory) bytes to be free to generate a 
  1312. library. 
  1313.  
  1314. The time D->LIB needs for doing a job depends mainly on the total number of 
  1315. commands included in the resulting library. Eg. Raymond runs D->LIB on a 
  1316. ~60kb directory containing ~300 variables; D->LIB needs ~15min on a rev A 
  1317. '48 to make the library (not in FAST-mode). Of course, this is quite faster 
  1318. than using USRLIB.EXE !!! 
  1319.  
  1320. Reassembling a split library may be dangerous if the original library was 
  1321. not generated using USRLIB.EXE or D->LIB. There is no guarantee that the 
  1322. result will work properly - even if no code changes are done. 
  1323.  
  1324. USRLIB.EXE generates a link table entry for the configuration program; if you 
  1325. split such a library with L->DIR, you'll get the configuration code twice, 
  1326. the first one stored in $CONFIG, the second one stored in a variable of the 
  1327. generated directory. Purge the variable before using D->LIB. You also can 
  1328. use LIBp to see the second reference to the config code. 
  1329.  
  1330.  
  1331. Appendix A - Quick Reference Guides 
  1332. ííííííííííííííííííííííííííííííííííí 
  1333.  
  1334.  
  1335. A.1 <-RPL-> 
  1336. ÄÄÄÄÄÄÄÄÄÄÄ 
  1337.  
  1338.  
  1339. A.1.1 Commands 
  1340. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  1341.  
  1342. Page 1234.1 
  1343.  
  1344.     RPL->    ( ob        --> $        )    decompile object 
  1345.     ->RPL    ( $        --> ob        )    compile object 
  1346.     DCADR    ( hxs        --> $ hxs'    )    decompile one word 
  1347.     COD->    ( code        --> $        )    disassemble CODE 
  1348.     ->COD    ( $        --> code libdat    )    assemble CODE 
  1349.     ->OB    ( ob        --> ob'        )    convert object 
  1350.  
  1351. Page 1234.2 
  1352.  
  1353.     DAN        ( hxs %n    --> $1 .. $n hxs' )    disassemble n times 
  1354.     DA1        ( hxs        --> $ hxs'    )    disassemble one mnemo 
  1355.     DAXY    ( hxs hxs    --> $        )    disassemble block 
  1356.     SYM->    ( libdat    --> $        )    convert symbol table 
  1357.     $->        ( $        --> ob        )    hex-dump to object 
  1358.     ->$        ( ob        --> $        )    object to hex-dump 
  1359.  
  1360. Page 1234.3 
  1361.  
  1362.     EC        (        --> ?        )    entries catalog 
  1363.     E<->A    ( hxs | $name    --> $name | hxs    )    get name/address 
  1364.     RPLtab    (        --> $        )    recall ref. table 
  1365.     4/5/7    (        -->        )    sys-stack display 
  1366.     CC        (        --> ?        )    character set catalog 
  1367.  
  1368.  
  1369. A.1.2 Flag Usage 
  1370. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  1371.  
  1372. General: 
  1373.  
  1374.     Flag    Meaning 
  1375.     ÄÄÄÄ        ÄÄÄÄÄÄÄ 
  1376.      -4        If set, RPL->/DCADR are using the disassembler to decompile 
  1377.         code objects. 
  1378.     -13        Quiet mode if set. The status report of RPL->, ->RPL, COD-> 
  1379.         and ->COD is suppressed. 
  1380.      64        Reserved. 
  1381.      63        Toggles sys-stack between 5/7 lines mode. 
  1382.      62        Set by 4/5/7 to signal an active medium font display. Can 
  1383.         be cleared to quit the sys-stack. 
  1384.      61        Toggles the behaivior of the down arrow key during sys-stack 
  1385.         display, the EDIT menu key during the sys-i-stack and the 
  1386.         ENTER key when finishing a command line. If set, you can edit 
  1387.         objects in sys-RPL syntax. A menu toggle for this flag can be 
  1388.         found on the 3rd page of the i-stack menu (labeled S-ED). 
  1389.  
  1390. DAN and DA1 are using the following flags: 
  1391.  
  1392.     Flag (set)    Meaning 
  1393.     ÄÄÄÄÄÄÄÄÄÄ  ÄÄÄÄÄÄÄ 
  1394.       1     next instr is a GO/RET YES/NO 
  1395.       2         last instr was RET... 
  1396.       3     last instr was GO C/NC/TO 
  1397.       4     last instr was relative GOSUB 
  1398.       5     last instr was absolute GO 
  1399.       6     last instr was PC manipulation 
  1400.       7     used internaly 
  1401.       8     last instr was absolute GO or Dx=(5) 
  1402.  
  1403.  
  1404. A.1.3 Error Messages 
  1405. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  1406.  
  1407. General Errormessages: 
  1408.  
  1409.     "Undefined XLIB Name" 
  1410.     Requests to execute a command when the <-RPL-> library is not attached 
  1411.     to the HOME directory will cause this error. See section 1.3. 
  1412.  
  1413.     "Need Binary Number" 
  1414.     The object passed to DCADR or DA1 isn't a binary number. 
  1415.  
  1416.     "Need String" 
  1417.     The object passed to ->RPL, ->COD or $-> isn't a string. 
  1418.  
  1419.     "Data Modifies Stack" 
  1420.     The object stored in RPL.TAB or ECpar doesn't add one item to the 
  1421.     stack. 
  1422.  
  1423.     "Where's your Program ?" 
  1424.     The string passed to ->RPL results to nothing. 
  1425.  
  1426.     "Primitive Code Object" 
  1427.     The object passed to RPL-> or the address passed to DCADR points to 
  1428.     a PCO. 
  1429.  
  1430.     "Found ACPTR on a SX" 
  1431.         RPL-> can't decompile ACPTR (ie. EXT1 objects) if <-RPL-> is installed 
  1432.         on a '48SX. 
  1433.  
  1434. ->COD Errormessages: 
  1435.  
  1436.     ->COD generates error messages of the following form: 
  1437.     "->COD Error: x:yy 
  1438.      Message" 
  1439.     where 'x' is the INCLUDE nesting depth and 'yy' is the character offset of 
  1440.     the first character following the token that caused the error. 'Message' 
  1441.     may be one of the following: 
  1442.  
  1443.     "ENDIF Expected"        an IF isn't matched by an ENDIF 
  1444.     "ENDIF w/o IF"        missplaced ENDIF 
  1445.     "ELSE w/o IF"        missplaced ELSE 
  1446.     "Invalid Parameter"        invalid parameter field 
  1447.     "Inv. Expr: expr"        invalid parameter field expression <expr> 
  1448.     "Invalid Mnemonic"        invalid menemonic 
  1449.     "Duplicate Label"        double defined label 
  1450.     "GOYES/RTNYES Expected"    comparisation without a following 
  1451.                 conditional jump 
  1452.     "GOYES out of range"    jump destination is more than -128/+127 
  1453.                 nibbles away 
  1454.     "Parameter Expected"    parameter of a mnemonic which expects 
  1455.                 one is missing 
  1456.     "Unknown Symbol: symb"    unknown symbol <symb> in an expression 
  1457.     "Inv. $: str"        invalid string <str> constant 
  1458.     "No IF Nesting Yet"        nesting of conditional IF .. ELSE .. ENDIF 
  1459.                 structures is not allowed (yet) 
  1460.     "Can't INCLUDE: nam" 
  1461.     There's no variable with the name <nam> 
  1462.  
  1463. ->RPL Errormessages: 
  1464.  
  1465.     ->RPL generates error messages of the following form: 
  1466.     "->RPL Error: x:yy 
  1467.      Message" 
  1468.     where 'x' is the INCLUDE nesting depth and 'yy' is the character offset of 
  1469.     the first character following the token that caused the error. Note that 
  1470.     if the error is generated by the asssembler (called by ->RPL to assemble 
  1471.     inline code), 'yy' is the error position relative to the first char after 
  1472.     the CODE or ASSEMBLE token. 'Message' may be one of the following 
  1473.     (additional to the ones listed for ->COD): 
  1474.  
  1475.     ") Expected" 
  1476.     Missing a ) to terminate a comment 
  1477.  
  1478.     "" Expected" 
  1479.     Missing a " to terminate a string 
  1480.  
  1481.     "ENDCODE Expected" 
  1482.     Missing the token ENDCODE to terminate a CODE statement 
  1483.  
  1484.     "RPL Expected" 
  1485.     Missing the token RPL to terminate a ASSEMBLE statement 
  1486.  
  1487.     "Misplaced ; or }" 
  1488.     Found a ; or } without a opening ::, {, UNIT or SYMBOL 
  1489.  
  1490.     "Suspect %" 
  1491.     "Suspect %%" 
  1492.     Parsing of a number results in an object of incorrect type 
  1493.  
  1494.     "Body Len <> Datalen" 
  1495.     The length field of a HXS-like styled statement is not equal to 
  1496.     the data length 
  1497.  
  1498.     "ACPTR is a G object" 
  1499.     ACPTR can only be compiled, if <-RPL-> is installed on a GX 
  1500.  
  1501.     "EXT1 is a S object" 
  1502.     EXT1 can only be compiled, if <-RPL-> is installed on a SX 
  1503.  
  1504.     "More Tokens Expected" 
  1505.     The statement at the end of the input string is incomplete 
  1506.  
  1507.     In the following messages 'ttt' represents the token that causes the 
  1508.     error: 
  1509.  
  1510.     "ROMP LibID >FFF: ttt" 
  1511.     "ROMP ROMWD >FFF: ttt" 
  1512.     The library ID part or the ROM word number part of a ROMPTR statement 
  1513.     is > FFF 
  1514.  
  1515.     "Suspect \ Seq: ttt" 
  1516.     The escape sequence ttt in the string, ID or LAM is incomplete or 
  1517.     invalid 
  1518.  
  1519.     "Can't INCLUDE: ttt" 
  1520.     "Can't INCLOB: ttt" 
  1521.     There's no variable with the name ttt 
  1522.  
  1523.     "Cont. no $: nam" 
  1524.     The INCLUDEd variable <nam> doesn't contain a string 
  1525.  
  1526.     "Inv. xxx: ttt" 
  1527.     where 'xxx' is one of the following: 
  1528.  
  1529.     "Tok"    - ttt is unresolvable 
  1530.     "#"    - ttt is out of range or contains chars other than hex digits 
  1531.     "$"    - ttt doesn't start with a " 
  1532.     "%","%%"- ttt represents an invalid number 
  1533.     "PTR"    - ttt is out of range or contains chars other than hex digits 
  1534.     "CHR"    - ttt contains more than one char 
  1535.  
  1536.     "Body Dat" - the data field of a HXS-like styled statement contains 
  1537.              chars other than hex digits 
  1538.     "Body len" - the length field of a HXS-like styled statement contains 
  1539.              chars other than hex digits 
  1540.     "RomWd"    - the ROM word number field of a ROMPTR is longer than 5 
  1541.              chars or contains chars other than hex digits 
  1542.     "LibID"    - the library ID field of a ROMPTR is longer than 5 chars 
  1543.              or contains chars other than hex digits 
  1544.     "APaa"     - the access address field of an ACPTR is longer than 5 
  1545.              chars or contains chars other than hex digits 
  1546.     "APda"     - the data address field of an ACPTR is longer than 5 
  1547.              chars or contains chars other than hex digits 
  1548.  
  1549.  
  1550. A.2 <-LIB-> 
  1551. ííííííííííí 
  1552.  
  1553.  
  1554. A.2.1 Commands 
  1555. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  1556.  
  1557. Page 1221.1 
  1558.  
  1559.     D->LIB    (        --> lib        )    build library 
  1560.     L->DIR    ( %        --> dir        )    split library 
  1561.     MCFG    (        -->        )    make config program 
  1562.     ML->D    (        --> prg        )    make libdat-> handler 
  1563.     MD->L    (        --> prg        )    make ->libdat handler 
  1564.     OB->    ( ob        --> ?        )    split object 
  1565.  
  1566. Page 1221.2 
  1567.  
  1568.     ->DIR    ( meta(ob,id)    --> dir        )    make directory 
  1569.     ->PRG    ( meta(ob)    --> prg        )    make program 
  1570.     ->XLIB    ( % % | # #    --> xlib    )    make XLIB 
  1571.     ->ARR    ( meta(ob)    --> arry    )    make array 
  1572.     ->ALG    ( meta(ob)    --> alg        )    make algebraics 
  1573.     ->LD    ( {} %        --> libdta    )    make library data 
  1574.  
  1575. Page 1221.3 
  1576.  
  1577.     ->BAK    ( ob $        --> bak        )    make backup 
  1578.     ->ID    ( $        --> id        )    make identifier 
  1579.     ADRp    ( ob        --> ob #    )    get address of object 
  1580.     $romid    (        --> id        )    get id '$ROMID' 
  1581.     $visible    (        --> id        )    get id '$VISIBLE' 
  1582.     $title    (        --> id        )    get id '$TITLE' 
  1583.  
  1584. Page 1221.4 
  1585.  
  1586.     $config    (        --> id        )    get id '$CONFIG' 
  1587.     $vars    (        --> id        )    get id '$VARS' 
  1588.     $hidden    (        --> id        )    get id '$HIDDEN' 
  1589.     $message    (        --> id        )    get id '$MESSAGE' 
  1590.     LBCRC    ( lib | bak    --> lib' | bak'    )    recalculate CRC 
  1591.     RNLIB    ( lib $        --> lib'    )    rename library 
  1592.  
  1593. Page 1221.5 
  1594.  
  1595.     CHLID    ( lib %        --> lib'    )    change LID 
  1596.     RHASH    ( %        --> C#        )    get hash table 
  1597.     RLINK    ( %        --> C#        )    get link table 
  1598.     RCFG    ( %        --> prg        )    get config code 
  1599.     RMSG    ( %        --> arry    )    get message table 
  1600.     RTITLE    ( %        --> $        )    get title 
  1601.  
  1602. Page 1221.6 
  1603.  
  1604.     RPORT    ( %        --> ob ...    )    recall port 
  1605.     RLIB    ( %        --> lib % ...    )    recall library(s) 
  1606.     PGLIB    ( % | :%:%    -->        )    purge library 
  1607.     STLIB    ( lib %        -->        )    store library 
  1608.     ACLIB    ( :%:%        -->        )    activate library 
  1609.     LIBp    ( %        --> $        )    get library layout 
  1610.  
  1611. Page 1221.7 
  1612.  
  1613.     INSTp    (        --> {}        )    get installed LIDs 
  1614.     LIBSp    (        --> {}        )    get all LIDs on 48 
  1615.     fEVAL    ( ob        --> ?        )    fast EVAL 
  1616.  
  1617.  
  1618. A.2.2 Flag Usage 
  1619. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  1620.  
  1621. 5    Set:    STLIB executes config code of passed library after 
  1622.         installation. 
  1623.         ACLIB executes config code of activated library. 
  1624.         <-LIB->s config code displays a (c) notice. 
  1625.     Clear:    STLIB and ACLIB are simply attaching the handled library 
  1626.         to the HOME directory. 
  1627.         <-LIB->s config code doesn't display (c) notice. 
  1628.  
  1629. 6    Set:    L->DIR places the $control variables at the end of the 
  1630.         generated directory. 
  1631.     Clear:    L->DIR places the $control variables at the beginning of 
  1632.         the generated directory. 
  1633.  
  1634. 7    Set:    L->DIR generates a $HIDDEN but no $VISIBLE variable. 
  1635.     Clear:    L->DIR generates a $VISIBLE but no $HIDDEN variable. 
  1636.  
  1637. -13    Set:    D->LIB/L->DIR switch the display off while processing 
  1638.         a directory/library (fast mode). 
  1639.     Clear:    D->LIB/L->DIR are leaving the display on while working. 
  1640.  
  1641.  
  1642. A.2.3 Error Messages 
  1643. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 
  1644.  
  1645. "Missing $ROMID" 
  1646.     $ROMID is not defined in the current directory 
  1647.  
  1648. "$ROMID Not Real/Binary" 
  1649.     $ROMID doesn't contain a % or HXS object 
  1650.  
  1651. "$ROMID Out of Range" 
  1652.     a) the value of $ROMID is > 2047 
  1653.     b) a % > 2047 was passed to CHLID 
  1654.  
  1655. "$CONFIG Not a Program" 
  1656.     Because the stack must not change during warmstarts, $CONFIG must contain 
  1657.     a program 
  1658.  
  1659.     Note: Use 1 ->PRG to embedd CODE, IDs or XLIBs into a program. 
  1660.  
  1661. "$HIDDEN Not a List" 
  1662. "$VISIBLE Not a List" 
  1663. "$VARS Not a List" 
  1664. "$MESSAGE Not a List" 
  1665.     $XXX must contain a list 
  1666.  
  1667. "Found ID Name>16 Chars" 
  1668.     D->LIB have found a visible command name which is > 16 chars in size 
  1669.  
  1670. "Found 0-ID" 
  1671.     D->LIB have found a visible command name with the size 0 
  1672.  
  1673. "Won't work on a G" 
  1674.     The initiated operation can't be executed on a '48G(X). 
  1675.  
  1676.  
  1677. Appendix B - A ->COD Example 
  1678. íííííííííííííííííííííííííííí 
  1679.  
  1680.  
  1681. Key in the following text (including the string delimiters) on your '48 (you 
  1682. may leave out the comments): 
  1683.  
  1684. "       GOSBVL  =SAVPTR         ** Save RPL pointers in save locations 
  1685. **                   P is 0 , HEX mode enabled 
  1686.     LAHEX    123AFE        ** Load HEX nibbles into A Register 
  1687. **                   starting at P 
  1688.     P=    5        ** 
  1689.     GOVLNG    =PUSHhxsLoop    ** Push A[WP] onto Data stack 
  1690. **                   and pass control to RPL 
  1691. " 
  1692.  
  1693. Store it in the variable SRC1. Recall the text to the stack, then press 
  1694. [->COD]. The display will show 'ASSEMBLER PASS 1' on the bottom line. In the 
  1695. upper part of the display 'Line  nnn' will appear, where <nnn> represents 
  1696. the actual code line to be assembled (empty lines or comment lines are not 
  1697. counted). 
  1698.  
  1699. A second later the display will show 'ASSEMBLER PASS 2' on the bottom line 
  1700. and 'Processing nnn Lines' in the message area. Another second later the 
  1701. source will have been assembled and the the string will be replaced by a 
  1702. 'Code' object and a 'Library Data' object. The stack should look as follows: 
  1703.  
  1704. úÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  1705. 3                     3 
  1706. ~AÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ' 
  1707. 34:                   3 
  1708. 33:                   3 
  1709. 32:               Code3 
  1710. 31:       Library Data3 
  1711. 3## ### ### ### ### ##3 
  1712. àÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  1713.  
  1714.  
  1715. The Library Data object contains all used local symbols (eg. labels). For the 
  1716. above example, it is an empty string, as there are no local symbols. The Code 
  1717. object represents the assembled source text. DROP the Library Data object and 
  1718. store the Code object into 'XQ1', then press the menu key [XQ1] . The stack 
  1719. now looks like: 
  1720.  
  1721. úÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  1722. 3                     3 
  1723. ~AÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ' 
  1724. 34:                   3 
  1725. 33:                   3 
  1726. 32:                   3 
  1727. 31:          # 123AFEh3 
  1728. 3## ### ### ### ### ##3 
  1729. àÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  1730.  
  1731.  
  1732. Now lets change example 1 to make use of the symbolic facilities of SASM48. 
  1733. First recall [SRC1] and edit the string: 
  1734.  
  1735. " 
  1736. hexdig    EQU    #123AFE 
  1737. pHXS    EQU    5 
  1738.     GOSBVL    =SAVPTR     ** Save RPL pointers in save locations 
  1739. **                   P is 0 , HEX mode enabled 
  1740.     LA(6)    hexdig        ** Load 6 HEX nibbles (represented by hexdig) 
  1741. **                   into A Register , starting at P 
  1742.     P=    pHXS        ** Set P to the value specified by pHXS 
  1743.     GOVLNG    =PUSHhxsLoop    ** Push A[WP] onto Data stack 
  1744. **                   and pass control to RPL 
  1745. " 
  1746.  
  1747. Store the string in SRC2, recall it back to the stack, then press [->COD]. 
  1748. The result looks like the result of example 1 except that the Library Data 
  1749. now contains the values of the defined labels. When the stack shows: 
  1750.  
  1751. úÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  1752. 3                     3 
  1753. ~AÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ' 
  1754. 34:                   3 
  1755. 33:                   3 
  1756. 32:               Code3 
  1757. 31:       Library Data3 
  1758. 3## ### ### ### ### ##3 
  1759. àÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  1760.  
  1761. press [SYM->] (located on the second menu page). The display changes to: 
  1762.  
  1763. úÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  1764. 3                     3 
  1765. ~AÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ' 
  1766. 34:                   3 
  1767. 33:                   3 
  1768. 32:               Code3 
  1769. 31: "hexdig  EQU   #..3 
  1770. 3## ### ### ### ### ##3 
  1771. àÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  1772.  
  1773.  
  1774. Press the down-arrow key: 
  1775.  
  1776. úÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  1777. 3                  prg3 
  1778. ~AÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ' 
  1779. 3                     3 
  1780. 3                     3 
  1781. 3"hexdig  EQU   #123..3 
  1782. 3pHXS    EQU   #5     3 
  1783. 3## ### ### ### ### ##3 
  1784. àÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  1785.  
  1786. This is the symbol table for SRC2. Press ATTN to return to the stack. DROP 
  1787. the string in level 1 and store the Code object into 'XQ2'. Press [XQ2]. You 
  1788. will get the same result as in example 1 because it's the same machine 
  1789. language program. 
  1790.  
  1791. You could even use [COD->] to disassemble the Code object in level 1. 
  1792.  
  1793.  
  1794. Appendix C - Ordering Information 
  1795. ííííííííííííííííííííííííííííííííí 
  1796.  
  1797.  
  1798. The sources of the <-RPL-> and the <-LIB-> libraries consists of more than 
  1799. 18000 lines of RPL/assembler code (that's more than 300kb of text !) and we 
  1800. have spent our free time for more than two years in writing RPL48, so we 
  1801. decided to release this version as GiftWare - ie. you can use RPL48 as long 
  1802. as you like but only for developing non-comercial software and only as a 
  1803. private person. 
  1804.  
  1805. If you think RPL48 is useful and that the authors deserve to be rewarded for 
  1806. the time they have invested in developing this toolkit, feel free to send 
  1807. one of us (or both ;-) any sort of gift (even only a postcard will be 
  1808. welcome). 
  1809.  
  1810. If your gift covers the expense sending you a disk via SnailMail (costs 
  1811. are: the disk, an envelope, the stamp and our time -> ~$25 or something 
  1812. equivalent), we will send you the latest *whole* version of RPL48 on a 
  1813. MesS-DOS formatted disk (including the <-RPL-> library branded with your 
  1814. name in the startup message). Don't forget to include your name, address 
  1815. and the disk size you prefer. 
  1816.  
  1817. Developping commercial software using RPL48 requires registration via the 
  1818. GiftWare concept; companies must send us at least a $50-worth gift for 
  1819. registration. 
  1820.  
  1821. Planned for the future are: 
  1822.     - better ARRY support in <-RPL-> 
  1823.     - maybe a DIR support in <-RPL-> 
  1824.     - a built-in system RPL debugger (hairy) 
  1825.     - a string editor (hairy) 
  1826.     - better GX port of <-LIB-> 
  1827.  
  1828. (all without guaranteeing the implementation) 
  1829.  
  1830. Contact addresses: 
  1831.  
  1832.     Detlef Mueller 
  1833.     Bellerbek 33 
  1834.     D-22559 Hamburg 
  1835.     Germany 
  1836.  
  1837.     Tel:    +49 40 811 92 80    8:00pm - 0:00am CET + 1h ds 
  1838.     FAX:    +49 40 589 58 199 
  1839.     e-mail:    detlef@dmhh.hanse.de 
  1840.  
  1841.  
  1842.     Raymond Hellstern 
  1843.     Liebigstr. 8 
  1844.     D-30163 Hannover 
  1845.     Germany 
  1846.  
  1847.     Tel./FAX +49 511 66 10 11 
  1848.